home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / FAQs / SGIfaqs / DSO-faq next >
Text File  |  1994-08-01  |  43KB  |  948 lines
  1.  
  2.       The following excerpt hails from "Chapter 3" of the "IRIX 5.1 IDO 
  3.          Release Notes," and is followed by "Appendix A" which is the 
  4.         Dynamic Shared Objects--DSOs--Frequently Asked Questions list.
  5.  
  6.  
  7.  
  8.  ______________________________________________________________________________
  9.  
  10.  
  11.                          "Dynamic Linking and DSOs"
  12.  
  13.    In previous versions of IRIX (pre-5.0), executables were only "statically
  14.    linked".  This means that all references must be resolved (and their 
  15.    addresses fixed) at link time (by LD(1)).  In this release, such 
  16.    programs, although they might use pre-5.0 shared libraries (which are 
  17.    referred to now as "static shared libraries") are referred to as "non-
  18.    shared".  They are produced by compiling and linking with the 
  19.    "-non_shared" option.  The code so created is *not* position-independent 
  20.    (PIC).
  21.    
  22.    In 5.0 and later IRIX releases, in addition to being statically linked by
  23.    LD(1), programs are, by default, compiled as PIC code and "dynamically 
  24.    linked", that is, part of the program may be relocated dynamically at run
  25.    time.  There are two types of dynamically linked objects:
  26.  
  27.      * The executable itself.  This consists of your main program and 
  28.        PIC code extracted from all archive libraries linked with it.  
  29.        Code within the executable is not relocated at run time, but 
  30.        some of its references will be.  The executable is linked 
  31.        "-call_shared".
  32.  
  33.      * External sharable dynamically linked objects called "dynamic 
  34.        shared objects" (DSOs), which are not part of the executable 
  35.        itself.  DSOs and their references may be dynamically relocated 
  36.        at run time.  DSOs are linked "-shared".  DSOs by convention 
  37.        have the extension ".so".  A DSO may be shared by several users 
  38.        and/or programs, possibly at different addresses.
  39.  
  40.    You cannot mix "non-shared" objects and PIC objects in the same 
  41.    executable.
  42.  
  43.    On this and future release, "static shared libraries" are supported only
  44.    for the use of existing (pre-5.0) executables that reference them.  You
  45.    can neither create new static shared libraries nor link new code with 
  46.    existing static shared libraries.
  47.  
  48.    PIC code satisfies references indirectly by using a Global Offset Table 
  49.    (GOT), which allows code to be relocated simply by updating the GOT.  
  50.    Your executable has one GOT, and each DSO it uses has one GOT.
  51.  
  52.    When a dynamically linked executable is started, the run-time linker, 
  53.    RLD(1), is invoked to prepare the program for execution.  This 
  54.    preparation involves:
  55.  
  56.      * Filling in certain global values.
  57.  
  58.      * Relocating any dynamic shared objects (DSOs) that your program 
  59.        references.
  60.  
  61.      * Resolving data symbols in DSOs that were unresolved at static 
  62.        link time by LD(1).
  63.  
  64.    With very few exceptions, all executable objects in this release are 
  65.    dynamically linked.  A new component, the run-time linker /lib/rld, and 
  66.    all standard DSOs (file extension ".so") are necessary for programs to 
  67.    execute.  
  68.  
  69.    More information about these types of objects appears in Appendix A, 
  70.    "Frequently Asked Questions about DSOs," (include below) and in the 
  71.    "IRIX Programming Guide".
  72.             
  73.             
  74.                         "Object File Format Changes"
  75.  
  76.    The compiler tools and the link editor now produce ELF format objects and
  77.    executables by default.  DSO is supported only in ELF executables and 
  78.    object files.  COFF files are run on IRIX 5.0 with the IRIX 4.0.5 ABI, 
  79.    and ELF files are run with the IRIX 5.0 ABI;  hence, the linker refuses 
  80.    to mix (pre-5.0) COFF and ELF objects.
  81.  
  82.    Two new header files are associated with ELF objects: 
  83.    /usr/include/elf_abi.h contains definitions that are generic to all 
  84.    implementations.  /usr/include/elf_mips.h contains definitions specific 
  85.    to the MIPS architecture.  See the "System V Application Binary 
  86.    Interface" and "System V Application Binary Interface MIPS Processor
  87.    Supplement", published by UNIX System Laboratories, for details.
  88.  
  89.    A new object file reader, ELFDUMP(1), is associated with ELF format 
  90.    files.  This program is known on some other SVR4-compliant systems as 
  91.    "dump".  
  92.  ______________________________________________________________________________
  93.  
  94.  
  95.  
  96.                 =============================================
  97.                     Frequently Asked Questions about DSOs
  98.                 =============================================
  99.  
  100.  
  101.  
  102.  
  103.    This list hails from the IRIX 5.2 DSO man page, begins near the top of
  104.    page 5, and constitues the remaining 15+ pages of this manual page. 
  105.  
  106.  
  107. FREQUENTLY ASKED QUESTIONS
  108. List of Questions:
  109.  
  110.    1)  What is DSO?
  111.    2)  How do dynamic shared objects compare with shared libraries?
  112.    3)  How do I maintain binary compatibility between versions of
  113.      dso's?"
  114.  
  115.    4)  Under which versions of the OS can I use DSO?
  116.    5)  What object-file format does DSO use?
  117.    6)  How do I install the tools so I can use DSO on my system?
  118.    7)  How do I build an executable that uses a shared object?
  119.    8)  How do I build an executable that doesn't use shared
  120.      linking?"
  121.  
  122.    9)  How do I tell if an executable will use dynamic linking?
  123.    10) How do I build a shared object?
  124.    11) Where does the system look for shared objects at runtime?
  125.    12) What is Quickstart?
  126.    13) What is the so_locations file?
  127.    14) What directives can be put in a so_locations file?
  128.    15) What is /usr/lib/so_locations?
  129.    16) If I don't have a valid so_locations, can I generate one from
  130.      all the .so's in, say, /usr/lib?"
  131.  
  132.    17) How expensive is it (at runtime) to NOT use the
  133.      -update_registry option?"
  134.  
  135.    18) How and when will Quickstart be used?
  136.    19) What about run-time loading under user control?
  137.    20) What benefits will I get from DSO?
  138.    21) What costs are associated with DSO?
  139.    22) What is the -KPIC option?
  140.    23) Must main programs which want to use DSO's use -KPIC for
  141.      compilation?"
  142.  
  143.    24) How do I change my assembly language sources to use -KPIC?
  144.    25) Can I mix IRIX 4 static shared libraries with DSO's?
  145.    26) What options do I have when building a shared object?
  146.    27) What pitfalls should I know about which are associated with
  147.      DSO?"
  148.  
  149. Page 5                           Release 5.2
  150.  
  151. DSO(5)                         Silicon Graphics                         DSO(5)
  152.  
  153.    28) What should I do about a GOT overflow?
  154.    29) How are multiple versions of DSO's supported?
  155.    30) Where can I find more documentation on DSO?
  156.    1)  What is DSO?
  157.      DSO stands for Dynamic Shared Objects.  DSO provides a capability similar
  158.      to static shared libraries under Cypress and earlier versions of the
  159.      IRIX, e.g., it gives applications the ability to share the text of
  160.      heavily used libraries, which need not be included in the executable
  161.      file.  However DSO has two important distinctions from static shared
  162.      objects.
  163.  
  164.    2)  How do dynamic shared objects compare with shared libraries?
  165.      First, a dynamic shared object contains only position-independent code,
  166.      so that it may be mapped into the virtual address space of different
  167.      processes at different addresses and still be shared.  Second, dynamic
  168.      shared objects, and indeed the executable itself are mapped in by a
  169.      runtime loader, rld, which resides in memory in the same address space as
  170.      the executable.  This gives the system the ability to change the binding
  171.      of symbols during executions, at the request of the executing program.
  172.      This capability should prove useful across a large segment of
  173.      applications.
  174.  
  175.    3)  How do I maintain binary compatibility between versions of dso's?
  176.      As long as the shared objects maintain the same exported symbols, or
  177.      perhaps add new symbols without removing any or changing semantics, and
  178.      don't change exported structures, they will be binary compatible.
  179.      Ordering of symbols, routines, are irrelevant, as global data, etc.  We
  180.      are working on a system called Delta-C++ which should allow you to add to
  181.      exported classes without recompiling.
  182.  
  183.    4)  Under which versions of the OS can I use DSO?
  184.      DSO is available under IRIX versions 5.0 and later.  Programs built with
  185.      DSO will not work on earlier version of IRIX.
  186.  
  187.    5)  Which object-file format does DSO use?
  188.      DSO uses the ELF object file format, as defined in the SVR4 ABI.  ELF
  189.      objects cannot be run under IRIX 4.0.5 or earlier.
  190.  
  191.    6)  How do I install the tools so I can use DSO on my system?
  192.      IRIX 5.0 and later releases all support/use DSO's.  In order to compile
  193.      and build shared objects you will need to have the Developer's option
  194.      installed.
  195.  
  196.    7)  How do I build an executable that uses a shared object?
  197.               cc myfile.c -lmine
  198.  
  199.      This will link you with libmine.so and also with libc.so.1, if either are
  200.      available.  If no libmine.so is available, but there is a libmine.a, the
  201.      libmine.a will be used along with libc.so.1, and you will still get
  202.      dynamic linking.  If you wish to be explicit, add the -call_shared flag
  203.      to the cc line:
  204.  
  205. Page 6                           Release 5.2
  206.  
  207. DSO(5)                         Silicon Graphics                         DSO(5)
  208.  
  209.               cc -call_shared myfile.c -lmine
  210.  
  211.    8)  How do I build an executable that doesn't use shared linking?
  212.      Use the -non_shared flag:
  213.  
  214.               cc -non_shared myfile.c -lmine
  215.  
  216.    9)  How do I tell if an executable will use dynamic linking?
  217.      elfdump -o shows you the ELF program header.  This contains all the
  218.      information necessary for exec and rld to run the program/shared object.
  219.      Only a.outs which use dynamic linking will have a PHDR, INTERP, or
  220.      DYNAMIC entry.
  221.  
  222.      Here's an example, and a more detailed description of this stuff.
  223.  
  224.      % elfdump -o /bin/cat
  225.  
  226.                   ***PROGRAM HEADER***
  227. Type     Offset      Vaddr      Paddr     Filesz      Memsz      Align RWX
  228.    PHDR 0x00000034 0x00400034 0x00400034 0x000000c0 0x00000000 0x00000004 r--
  229.  INTERP 0x00000100 0x00400100 0x00400100 0x00000009 0x00000009 0x00000004 r--
  230. REGINFO 0x00000110 0x00400110 0x00400110 0x00000018 0x00000018 0x00000004 r--
  231. DYNAMIC 0x00000150 0x00400150 0x00400150 0x00000a70 0x00000a70 0x00000010 r--
  232.    LOAD 0x00000000 0x00400000 0x00400000 0x00003000 0x00003000 0x00001000 r-x
  233.    LOAD 0x00003000 0x10000000 0x10000000 0x00001000 0x00001290 0x00010000 rwx
  234.  
  235.      Each line is an entry in the program header, and refers to a "segment" of
  236.      the file.
  237.  
  238.      PHDR points to the program header itself within the file. Only
  239.           executables which use dynamic linking will have this field.
  240.  
  241.      INTERP
  242.           points to a place in the file where the name of the interpreter
  243.           required for this program is to be found.  For any ABI-conforming
  244.           object, this name will be "/usr/lib/libc.so.1".
  245.  
  246.      REGINFO
  247.           points to a place in the file where information about register setup
  248.           can be found.  Currently this mostly consists of the correct gp
  249.           value for this object.
  250.  
  251.      DYNAMIC
  252.           points to the information in the file which is needed by rld to
  253.           execute it correctly.  This information includes the liblist, a
  254.           symbol table, and other information.
  255.  
  256.      LOAD points to segments that are to be mapped into the memory image.
  257.  
  258. Page 7                           Release 5.2
  259.  
  260. DSO(5)                         Silicon Graphics                         DSO(5)
  261.  
  262.      The columns give various information about each segment.
  263.  
  264.      Offset
  265.           is the offset in the file to the beginning of the segment.
  266.  
  267.      Vaddr
  268.           is the virtual address of the beginning of the segment in the memory
  269.           image of the file, ASSUMING that it was mapped as described in the
  270.           LOAD entries
  271.  
  272.      Paddr
  273.           is the same as Vaddr in our implementation.
  274.  
  275.      Filesz
  276.           is the size of the segment in the file.
  277.  
  278.      Memsz
  279.           is the size of the segment in the memory image.  When this is larger
  280.           it is assumed to be zero-filled.
  281.  
  282.      Align
  283.           is the alignment required by this section.  If an segment is to be
  284.           mapped somewhere into memory other than at Vaddr, the new address
  285.           must be congruent to Vaddr modulo the alignment.  In the example
  286.           above, the first segment must always be loaded at a page boundary,
  287.           and the second must always be loaded at a 64K boundary.
  288.  
  289.      RWX  specifies the protections r(ead), w(rite), or x(ecute) for the
  290.           segment.
  291.  
  292.      Programs which are linked -non_shared do not have a PHDR, INTERP, or
  293.      DYNAMIC section.  Thus elfdump -o is a convenient method to determine if
  294.      a program is linked -non_shared or not.
  295.  
  296.    10) How do I build a shared object?
  297.      To begin with, build a .o or .a which contains all the routines you want
  298.      to have in your .so (shared object).  This can be done with cc -c and ar.
  299.      Then invoke ld with the -shared flag. Normally the extension .so is used
  300.      to designate shared objects.
  301.  
  302.      Here is an example:
  303.  
  304.          cc -c myobj.c
  305.          ld -shared myobj.o -o myobj.so
  306.  
  307.          -or-
  308.  
  309.          <build libmine.a the usual way.>
  310.          ld -shared -all libmine.a -o libmine.so
  311.  
  312. Page 8                           Release 5.2
  313.  
  314. DSO(5)                         Silicon Graphics                         DSO(5)
  315.  
  316.      The -all flag in the second example tells ld to include all the routines
  317.      in the library.  This is necessary since there are no undefined
  318.      references (in a main, say) which is the usual way that ld knows to
  319.      include files from an archive.
  320.  
  321.    11) Where does the system look for shared objects at runtime?
  322.      The search path for shared objects is acquired in the following order:
  323.  
  324.      1) the path of the shared object if given in the liblist,
  325.  
  326.      2) in any directories specified via the
  327.           -rpath flag when the executable was built
  328.  
  329.      3) in any directory specified by the LD_LIBRARY_PATH environment
  330.           variable, if it is defined
  331.  
  332.      4) in the directories in the default path
  333.           (/usr/lib:/lib:/lib/cc:/usr/lib/cc)
  334.  
  335.      If the _RLD_ROOT environment variable is defined, then its value is
  336.      appended to the front of any path specified by -rpath and the default
  337.      path.  _RLD_ROOT itself is also a colon(:) separated list.
  338.  
  339.      See the rld(1) manpage for details.
  340.  
  341.    12) What is Quickstart?
  342.      Quickstart is an optimization. Using the so_locations file, each shared
  343.      object is pre-relocated by ld, as if it had been loaded at the address in
  344.      the so_locations file.  That way, if nothing unusual happens when we
  345.      start up the application, all the shared objects will map at their
  346.      Quickstart addresses, and rld will not need to do a relocation pass over
  347.      them.
  348.  
  349.      If for some reason more than one shared object wishes to map the same
  350.      address, rld will move one of them to an unused address and perform a
  351.      relocation pass to fix up the address references.
  352.  
  353.      If one or more of the shared objects linked against at static link time
  354.      has changed by the time the program executes, rld will need to do extra
  355.      work to ensure that symbols have been resolved to their proper value.
  356.  
  357.    13) What is the so_locations file?
  358.      In the directory in which you build a shared object, after you've
  359.      actually built one, you will notice a file named so_locations.
  360.  
  361.      It is a registry of shared objects.  It maintains the default or
  362.      Quickstart addresses of a group of shared objects which are to cooperate
  363.      by not having their default location overlap with one another.  It is
  364.      generated and updated by ld each time it builds a shared object.
  365.  
  366. Page 9                           Release 5.2
  367.  
  368. DSO(5)                         Silicon Graphics                         DSO(5)
  369.  
  370.    14) What directives can be put in an so_locations file?
  371.      Comment line
  372.           so_name [ :st = { .text | .data | $range } base_addr,padded_size : ] *
  373.  
  374.      where
  375.           so_name         full path name (or trailing component) of a
  376.                           shared object
  377.           st              string identifying start of the segment description
  378.           .text | .data   segment types: text or data
  379.           $range           limit the range of address that can be used
  380.           base_addr       address where the segment starts
  381.           padded_size     padded size of the segment
  382.  
  383.      The following directives control the placement of new shared objects:
  384.  
  385.           $text_align_size=<align>  padding=<pad-size>
  386.           $data_align_size=<align>  padding=<pad-size>
  387.               These two directives specify the alignment and padding
  388.            requirements for text and data segments respectively.
  389.            The size value in so location is calculated based on:
  390.               (section size + padding) aligned to the section align size
  391.               The align values for text and data as well as the padding
  392.               values must be aligned to a bucket size. If not, ld will
  393.            generate a warning message and align these values to bucket
  394.            size.
  395.  
  396.           $start_address=<addr>
  397.               Specifies where to start looking for addresses to put shared
  398.               objects.
  399.  
  400.           $data_after_text=[ 1 | 0 ]
  401.               Instructs the linker to place data immediately after the text
  402.               at specified text and data alignment requirements.
  403.               We set the data_after_text to 0 if the argument of this directive
  404.               is missing.
  405.  
  406.      Also, when building a dso with the -check_registry or -update_registry
  407.      flag, and if there is already an entry corresponding to this dso in the
  408.      so_location file, the linker will try to assign the same addresses for
  409.      text and data.  However, if the size of the dso changes and does not fit
  410.      in the specified location any more, the linker will search for another
  411.      spot that fits.  If the optional $range comment is given, the linker will
  412.      only place the dso in the specified range of addresses.  If there is not
  413.      enough room, an error will be given.
  414.  
  415.    15) What is /usr/lib/so_locations?
  416.      This file represents the default layout for the system shared objects.
  417.      Developers who build shared objects may find it interesting to consult
  418.      this file, in order to avoid collisions between their shared objects and
  419.      system shared objects.  This file is absolutely irrelevant to users who
  420.      merely run programs which use shared objects.
  421.  
  422. Page 10                          Release 5.2
  423.  
  424. DSO(5)                         Silicon Graphics                         DSO(5)
  425.  
  426.      There are two options which are relevant, -update_registry, and <file>
  427.      looks at <file> and builds the current .so at a location which doesn't
  428.      conflict with anything in the file (unless the current one is listed.  -
  429.      check_registry does not write to <file>.  -update_registry <file> will
  430.      consult <file> as with -check_registry, but will attempt to write an
  431.      entry for the .so being built into <file>.  If <file> is not writable, -
  432.      update_registry turns into If <file> is not readable -check_registry and
  433.      -update_registry are ignored.
  434.  
  435.    16) If I don't have a valid so_locations file, can I generate one from all
  436.      the .so's in, say, /usr/lib?
  437.      There is no convenient method to do so.  There is no guarantee that all
  438.      the .so's in /usr/lib have been coordinated so that a consistent
  439.      so_locations file can be made from them.  So it is better to get the one
  440.      that a particular release was made with.
  441.  
  442.    17) How expensive is it (at runtime) NOT to use -update_registry option?
  443.      The costs are all startup costs.  It is very difficult to say how much a
  444.      particular executable will suffer since it depends on which shared
  445.      objects the program uses and whether they have been Quickstarted for the
  446.      same address.  When there is a conflict between two objects, one will be
  447.      moved, which means that all addresses referring to names in that object
  448.      need to be relocated.
  449.  
  450.    18) How and when will Quickstart be used?
  451.      Normally, the linker will use Quickstart unless there are unresolved
  452.      symbols at static link time.
  453.  
  454.      In every executable and every shared object is a list of objects which
  455.      were looked at at static link time -- when the object was made.  This
  456.      list also contains timestamps and checksums for each of the objects.
  457.      Various levels of extra work are required if the timestamp or checksum
  458.      has changed in the library at run-time.
  459.  
  460.    19) What about run-time loading under user control?
  461.      We support an interface known as libdl, which allows users to dynamically
  462.      load their own shared objects as needed. The calls are
  463.  
  464.      dlopen() -- open a new shared object and get a "handle" to it.
  465.  
  466.      dlsym()  -- find the value of a name defined in an object.
  467.  
  468.      dlclose()-- close a shared object.
  469.  
  470.      dlerror()-- report errors.
  471.  
  472.      sgidladd() -- functions much like dlopen however it exposes
  473.           all symbols to the rest of the program.
  474.  
  475.      Consult the individual manpages for details.
  476.  
  477. Page 11                          Release 5.2
  478.  
  479. DSO(5)                         Silicon Graphics                         DSO(5)
  480.  
  481.    20) What benefits will I get from DSO?
  482.      Executables linked with shared objects will be smaller since the shared
  483.      objects are not part of the executable file image.
  484.  
  485.      Executables which use a shared object need not be relinked if a shared
  486.      object is changed -- once the updated shared object is installed, the
  487.      executable will pick it up automatically.
  488.  
  489.      Shared libraries are much easier to build, use, and debug than static
  490.      shared libraries.
  491.  
  492.      DSO allows application designers to make more machine-independent
  493.      software.  System-dependent routines can be given a uniform interface and
  494.      a shared object which implements that interface can be built for each
  495.      different platform.  Then an actual application can be shipped as-is
  496.      ("shrink-wrapped" software) to various platforms and run on them all.
  497.  
  498.      DSO gives applications the ability to change the binding of symbols at
  499.      run time, under user control.
  500.  
  501.    21) What costs are associated with DSO?
  502.      A shared object incurs two costs, both against performance.
  503.  
  504.      At startup, there will be a startup cost while rld maps in the various
  505.      objects, performs symbol resolution, etc.  We believe this cost is small
  506.      compared to the time it takes to contact the X server, for example.
  507.      Quickstart will reduce this time for smaller applications.
  508.  
  509.      A shared object's text must be PIC (position independent code).
  510.      PICification is accomplished by the code generator (ugen) and assembler
  511.      (as), when the -KPIC flag is specified.  This is the default However, PIC
  512.      code is necessarily slower. Experiments have indicated that this speed
  513.      reduction is usually less than 5 percent, but can be as much as 15
  514.      percent.  depending on the application.  PIC code seems to be worst on
  515.      very small leaf routines which access global data.
  516.  
  517.    22) What is the -KPIC option?
  518.      This flags tells the code generator and assembler to generate PIC
  519.      directly.  The result is an object file that can be put into a DSO
  520.      without further modification
  521.  
  522.               cc -KPIC -c foo.c
  523.  
  524.      will give you a PIC object foo.o.  Other drivers (cc, pc, f77, and as)
  525.      also accept the -KPIC option.  This is the default.
  526.  
  527.      Routines written in assembly languages need to be modified before -KPIC
  528.      can be used. See the question below.
  529.  
  530.      PIC objects generated by using -KPIC must be compiled -G 0.
  531.  
  532. Page 12                          Release 5.2
  533.  
  534. DSO(5)                         Silicon Graphics                         DSO(5)
  535.  
  536.    23) Must main programs which want to use DSO's use -KPIC for compilation?
  537.      Yes.  DSO's use -KPIC so that position-independent code will be
  538.      generated.  Main programs are not generally position-independent, but
  539.      must still use the DSO calling convention when calling a routine which is
  540.      defined in a DSO. In particular, this means that a main program must have
  541.      a GOT, and the code which is generated must use it.  Therefore, modules
  542.      which will become part of main programs must be compiled -KPIC as well as
  543.      modules which become part of DSO's.
  544.  
  545.    24) How do I change my assembly language sources to use -KPIC?
  546.      Several new assembler directives are added to support generation of PIC.
  547.      You should also get yourself familiar with the MIPS ABI Supplement and
  548.      the PIC coding model it describes.  In addition, files which are to be
  549.      assembled with -KPIC must also be -G 0.  This is normally turned on by
  550.      the driver by default.
  551.  
  552.      Note that with the exception of (a) and (d), all other directives
  553.      described below will be ignored when -KPIC is not explicitly specified.
  554.      Also, item (d), ".gpword", will be turned into ".word". The result will
  555.      be a NON-PIC version of the same routine.
  556.  
  557.      a) .option pic2
  558.  
  559.      This directive forces the assembler to mark the output object file "PIC"
  560.      and activates the following directives.  It overrides the command line
  561.      argument.  Normally, you don't need to specify this directive.  Instead,
  562.      you should use the -KPIC or -non_shared flags to toggle between
  563.      generating PIC or non-PIC.
  564.  
  565.      Note that even though -KPIC will be made the default for the high-
  566.      language driver (cc/pc/f77) in future releases, it will *NOT* be the
  567.      default for assembly sources.  You will always have to explicitly specify
  568.      -KPIC for compiling .s files.
  569.  
  570.      b) .cpload reg
  571.  
  572.      This directive expands into three instructions that sets the gp register
  573.      to the context pointer value for the current function.  The three
  574.      instructions are:
  575.           lui  gp,_gp_disp
  576.           addui     gp,gp,_gp_disp
  577.           addu gp,gp,reg
  578.  
  579.      _gp_disp is a reserved symbol defined by the linker to be the distance
  580.      between the lui instruction and the context pointer.  This directive is
  581.      required at the beginning of each subroutine that uses the gp register.
  582.  
  583.      You must add this directive at the beginning of every procedure, with the
  584.      exception of leaf-procedures that do not access any global variables, and
  585.      procedures that are static (i.e., not marked .globl or .extern).
  586.  
  587. Page 13                          Release 5.2
  588.  
  589. DSO(5)                         Silicon Graphics                         DSO(5)
  590.  
  591.      c) .cprestore offset
  592.  
  593.      This directive causes the assembler to issue
  594.                sw   gp,offset(sp)
  595.      at the point where it appears.  Additionally, it causes the assembler to
  596.      emit
  597.                lw   gp,offset(sp)
  598.      after every jump-and-link (jal) or branch-and-link (bal) operation,
  599.      thereby restoring the gp register after function calls.  The programmer
  600.      is responsible for allocating the stack space for the gp.  This space
  601.      should be in the saved register area of the stack frame to remain
  602.      consistent with MIPS' calling and debugger conventions.
  603.  
  604.      d) .gpword local-sym
  605.  
  606.      This directive is similar to .word except that the relocation entry for
  607.      local-sym has the R_MIPS_GPREL32 type.  After linkage, this results in a
  608.      32-bit value that is the distance between local-sym and the context
  609.      pointer (i.e. the gp).  local-sym must be local.  It is currently used
  610.      for PIC switch tables.
  611.  
  612.      e) .cpadd reg
  613.  
  614.      This adds the value of the context pointer (gp) to reg.
  615.  
  616.      EXAMPLES:
  617.           This is a simplified version of the "hello world" program:
  618.           --------------------------------------------------------------
  619.                .option   pic2
  620.                .data
  621.                .align    2
  622.           $$5:
  623.                .ascii    "hello world\X0A\X00"
  624.                .text
  625.                .align    2
  626.           main:
  627.                .set  noreorder
  628.                .cpload   $25
  629.                .set  reorder
  630.                subu $sp, 40
  631.                sw   $31, 36($sp)
  632.                .cprestore     32
  633.                la   $4, $$5
  634.                jal  printf
  635.                move $2, $0
  636.                lw   $31, 36($sp)
  637.                addu $sp, 40
  638.                j    $31
  639.           ----------------------------------------------------------------
  640.           The actual instructions generated by the assembler will be:
  641.  
  642.                lui  gp,0      #
  643.  
  644. Page 14                          Release 5.2
  645.  
  646. DSO(5)                         Silicon Graphics                         DSO(5)
  647.  
  648.                addiu     gp,gp,0        # generated by .cpload
  649.                addu gp,gp,t9  #
  650.                lw   a0,0(gp)  # gp-relative addressing used
  651.                lw   t9,0(gp)  # t9 is used for func. call
  652.                addiu     sp,sp,-40
  653.                sw   ra,36(sp)
  654.                sw   gp,32(sp) # from .cprestore
  655.                jalr ra,t9          # jal is changed to jalr
  656.                addiu     a0,a0,0
  657.                lw   ra,36(sp)
  658.                lw   gp,32(sp) # activated by .cprestore
  659.                move v0,zero
  660.                jr   ra
  661.                addiu     sp,sp,40
  662.                nop
  663.           ----------------------------------------------------------------
  664.  
  665.      NOTE:
  666.  
  667.      The MIPS's ABI required register t9 ($25) be used for indirect function
  668.      call, so .cpload should always use $25.  No reorder mode should also be
  669.      used.  Also, programmers should make sure that t9 is dead before any
  670.      function call.
  671.  
  672.      If your program uses an indirect jump (jalr), you must also use t9 as the
  673.      jump register.
  674.  
  675.      If you have an unconditional jump to an external label:
  676.                j  _cerror
  677.          you have to rewrite it into indirect jump via t9, i.e.:
  678.                la t9,_cerror
  679.                j  t9
  680.  
  681.      If you use branch-and-link (bal) instruction, and if the target procedure
  682.      begins with a .cpload, you have to specify an alternate entry point:
  683.  
  684.           foo: .set noreorder # callee
  685.                .cpload   $25
  686.                .set reorder
  687.           $$1: ...            # alternative entry point
  688.                ...
  689.                j    $31       # foo returns
  690.  
  691.           bar: ...            # caller
  692.                ...
  693.                bal  $$1       # by-pass the .cpload
  694.                ...
  695.  
  696.      This is very important because .cpload assumes register $25 contains the
  697.      address of foo, but in this case $25 is not set up.  Note that since both
  698.      foo and bar reside in the same file, they must have the same value for
  699.      $gp.  So the .cpload instructions can be and must be bypassed.  However,
  700.  
  701. Page 15                          Release 5.2
  702.  
  703. DSO(5)                         Silicon Graphics                         DSO(5)
  704.  
  705.      since foo can still be called from outside, the .cpload is still
  706.      required.
  707.  
  708.      Alternatively, if you don't want to have an alternate entry point, you
  709.      can set up register $25 before the bal:
  710.                la   t9,foo
  711.                bal  foo
  712.  
  713.          but this will be less efficient.
  714.  
  715.      position-independent jump table (or any table of text addresses).
  716.      Entries of the address table created by .gpword are converted into
  717.      displacement from the context pointer.  To get the correct text address,
  718.      .cpadd should be used to add the value of gp back to them.  Since the gp
  719.      is updated by the run-time linker, the correct text address can be
  720.      reconstructed regardless of the location of the dso.
  721.  
  722.    25) Can I mix IRIX 4 static shared libraries with DSO's?
  723.      We do not anticipate ever allowing an a.out to use both static shared
  724.      libraries and dso.
  725.  
  726.    26) What options do I have when building a shared object?
  727.      If you specify the flag -B dynamic while linking a shared object, symbols
  728.      in the shared object will be resolved differently than the default
  729.      linkage convention.  In particular, the runtime linker will always try to
  730.      resolve any symbols referenced in that object to symbols defined in that
  731.      object first, instead of looking for definitions in objects in the order
  732.      specified on the link line.
  733.  
  734.      The effect of this is to make all symbols defined and used in such
  735.      objects non-preemptable.  Ordinarily a such symbol definitions could be
  736.      preempted by a definition in an earlier shared object, but when -B
  737.      symbolic is specified, this is not the case.
  738.  
  739.    27) What pitfalls are associated with DSO?
  740.      Behind most of the surprises that users will get is the fact that linking
  741.      semantics are fundamentally different, but only in a subtle way.  Let us
  742.      suppose that your program links with three libraries, libA, libB and
  743.      libC, in that order.  Further suppose that both libA and libC define some
  744.      symbol x, but don't use it.  Furthermore, let us suppose that libB
  745.      contains a reference to x.  Archive linking (the old way) will resolve
  746.      B's reference to x to the definition in C, whereas shared object linking
  747.      will resolve B's reference to x to the definition in A.
  748.  
  749.      Why the difference?  With archive linking, when libA is examined, there
  750.      is no outstanding reference to x, hence the definition of x is not
  751.      extracted from the archive.  Later when libC is examined, there is a
  752.      reference to x, so it is loaded.
  753.  
  754.      With shared objects, all the constituent object files have been joined
  755.      into one object, so all symbol definitions are always present.  The
  756.      resolution rule is simple, take the definition in the object listed
  757.  
  758. Page 16                          Release 5.2
  759.  
  760. DSO(5)                         Silicon Graphics                         DSO(5)
  761.  
  762.      first. Thus the definition in libA is used.
  763.  
  764.      Another sort of surprise is the "runtime dangling reference".  It is
  765.      altogether possible to build and link an application with no errors or
  766.      even warnings, only to get a message from rld stating that your program
  767.      has unresolvable symbols.
  768.  
  769.      What's going on?  Well, if you build a shared object as part of your
  770.      program, the linker will not normally complain about undefined symbols
  771.      during a link of a shared object.  This is because undefined symbols are
  772.      expected during such a build and are perfectly acceptable.  But if the
  773.      main program does not use a symbol, it does not get flagged as undefined
  774.      during static linking.  Thus the runtime "surprise".  You can use the -
  775.      no_unresolved flag to the linker to avoid such surprises.
  776.  
  777.      Now we get to a nasty pitfall which can be avoided by some cleverness in
  778.      building a shared object.  If a particular object in an archive has an
  779.      external reference to a data symbol (which it expects to be defined in
  780.      main, libl.a, for example) the linker would not try to resolve that
  781.      external unless the object file in question was actually referenced by
  782.      the main program.  Now if that archive is turned into a shared object
  783.      naively, the external data reference must be resolved whenever ANY
  784.      function in the shared object is used, even if no function in the object
  785.      file in question is ever called and no use is made of the external data
  786.      symbol in question.
  787.  
  788.      This can lead to a scenario where a user has a link that worked with the
  789.      archives, but builds a program which gets nuked by the runtime linker
  790.      under the new scheme of things.  I believe that it is a very bad idea for
  791.      us to convert libraries. such as libl.a, which contain external data
  792.      symbols, to shared objects naively.
  793.  
  794.      One thing that can be done is to split the archive into several shared
  795.      objects which are placed on the liblist of a "master" shared object.
  796.      Since rld will not by default try to resolve data symbols until the first
  797.      call is made to a particular object we can create the situation where no
  798.      attempt to resolve the offending external data symbol is made until a
  799.      call is made to the object in which it is referenced.
  800.  
  801.      Here's an example of how that works: Let us suppose that
  802.      has_extern_data.o is an object with an undefined external in it which
  803.      resides in the archive libxyz.a  Here is how to isolate that external
  804.      data reference:
  805.  
  806.      First make has_extern_data.o into a shared object all its own.
  807.  
  808.            % ar x libxyz.a has_extern_data.o
  809.            % ld -shared has_extern_data.o -o has_extern_data.so
  810.  
  811.      Now, make libxyz.so, excluding has_extern_data.o from being included
  812.      directly, but instead putting it in the liblist of libxyz.so
  813.  
  814. Page 17                          Release 5.2
  815.  
  816. DSO(5)                         Silicon Graphics                         DSO(5)
  817.  
  818.          % ld -shared -all -exclude has_extern_data.o libxyz.a has_extern_data.so      -o libxyz.so
  819.  
  820.    28) What should I do about a GOT overflow?
  821.      By default, addresses are loaded out of the Global Offset Table (GOT)
  822.      using a 16 bit offset from a context pointer.  This means that the size
  823.      of the GOT is limited (by default) to 64K bytes, or about 16 K symbols.
  824.      When there are too many symbols referenced by a DSO (or a.out) the linker
  825.      issues the messag "GOT overflows"  and will specify an object file which
  826.      references the symbol which is "out of reach".
  827.  
  828.      SGI recommends that when developers encounter this problem, they attempt
  829.      to split the DSO or a.out in question into several smaller DSO's, each of
  830.      which can conform to the GOT size limit.  Maximum performance can be
  831.      achieved this way.
  832.  
  833.      However, as an alternative, developers may wish to use the -xgot
  834.      compile-time flag to tell the compiler to issue a different (and slower)
  835.      code sequence uses a 32-bit offset.  This will allow the GOT to contain
  836.      up to 1G entries.  However, it is critical that every object linked into
  837.      a final DSO or a.out be compiled with -xgot turned on, otherwise code may
  838.      have been generated which will not work with an extended GOT.  However,
  839.      files compiled with -xgot may be linked into a DSO or a.out which has a
  840.      GOT that does not exceed the 16K limit and will work correctly, if
  841.      somewhat slower.  The GOT size of any shared objects linked is
  842.      irrelevant.
  843.  
  844.      The directory /usr/lib/xgot contains the extended-GOT versions of those
  845.      objects which SGI has built both normally and -xgot. If a system or third
  846.      party archive contains small GOT objects which are needed in an extended
  847.      GOT link, a developer can take the following steps: 1) Look in
  848.      /usr/lib/xgot to see if an extended GOT version exists.  2) Turn the
  849.      archive into its own shared object, thus isolating it from the extended
  850.      GOT binary. 3) contact the archive provider.  In a few cases (crt1.o,
  851.      crtn.o, c++init.o, and fixade.o), where the performance issues were
  852.      minimal,  the default objects in /usr/lib are in fact built large GOT.
  853.  
  854.    29) How are multiple versions of DSO's supported?
  855.      IRIX 5.0.1 (Compilers v3.16) and later supports the ability to tag shared
  856.      objects and executables with a version number.  This is intended to
  857.      support interface changes.  Details are below; items marked (SGI ONLY) do
  858.      not apply to MSIG ABI binaries, but only to binaries generated on IRIX
  859.      without the -abi flag turned on.
  860.  
  861.     Versioning of Shared Objects.
  862.  
  863.     QUICK OVERVIEW
  864.  
  865.     In order for a shared object to be versioned in the future
  866.     the following needs to be done:
  867.  
  868.     * Version strings consist of 3 parts and a dot: The string "sgi",
  869.       a decimal number (the major number), a dot, and a decimal number
  870.  
  871. Page 18                          Release 5.2
  872.  
  873. DSO(5)                         Silicon Graphics                         DSO(5)
  874.  
  875.       (the minor number).
  876.  
  877.     * Add the command -set_version sgi1.0 to the command to build
  878.       the shared object (cc -shared, ld -shared, etc.).
  879.  
  880.     * (Future) Whenever you make a COMPATIBLE change update the minor version
  881.       number (the one after the dot), and add the latest version string
  882.       to colon-separated list of version strings, e.g., -set_version
  883.       sgi1.0:sgi1.1:sgi1.3
  884.  
  885.     * (Future) Whenever you make an INCOMPATIBLE change, update the
  886.       major version number.  Pass this as the version list, e.g.,
  887.       -set_version sgi2.0.  Change the filename of the OLD shared object
  888.       by adding a dot followed by the previous major number to the filename
  889.       of the shared object.  DO NOT CHANGE the soname of the object.
  890.       No change to the file contents are necessary or desirable.  Simply
  891.       rename the file.
  892.  
  893.     HOW IT ALL WORKS
  894.  
  895.     * Versioning will only be available for NON-ABI executables.
  896.       The current ABI does not require objects to have versioning, nor
  897.       does it require systems to pay attention to versioning.  It does
  898.       allow objects to contain version strings, but does not require
  899.       systems to do anything with this information.
  900.  
  901.     * NON-ABI compliant executables will have a SGI_ONLY bit turned
  902.       on in the .dynamic section.  This flag will be understood and
  903.       reported by elfdump.  Only executables with this flag on will
  904.       get the versioning treatment described below.  This flag will
  905.       be on by default.
  906.  
  907.     * When an executable is linked against a shared object, the last
  908.       entry of the shared object's version string is recorded in the
  909.       executable as part of the liblist.  This can be examined by
  910.       elfdump -Dl.
  911.  
  912.     * When an executable is linked, the user may specify -require_minor or
  913.       -ignore_minor for each shared object linked against.  If
  914.       -require_minor is specified, a bit will be set in the flags field of
  915.       the liblist entry for the shared object in question.  The default
  916.       is -ignore_minor.
  917.  
  918.     * When an executable (ABI or SGI_ONLY) is run rld will look
  919.       for the proper filename in its usual search routine.
  920.  
  921.     * (SGI_ONLY) If a file with the correct name is found the
  922.       version string in the liblist is compared to the list
  923.       of version strings in the shared object.  If the REQUIRE_MINOR bit
  924.       is set in the liblist entry, and there is an exact match between the
  925.       version string in the depender and one of the strings in the version
  926.       list of the dependee, then that library is used.  If the
  927.  
  928. Page 19                          Release 5.2
  929.  
  930. DSO(5)                         Silicon Graphics                         DSO(5)
  931.  
  932.       REQUIRE_MINOR bit is clear, and if there is a match of major
  933.       versions, then that library is used.
  934.  
  935.     * (SGI_ONLY) If no proper match is found, a new soname is built
  936.       by taking the soname found in the executables liblist, and the
  937.       major number found in the version string corresponding to that
  938.       liblist entry, and putting them together as <soname>.<major>
  939.       This is searched for in the same way as above. Version strings are
  940.       matched in exactly the same way as described above.
  941.  
  942.    30) Where can I find more documentation on DSO?
  943.      Besides the other manpages mentioned below, System V Application Binary
  944.      Interface and System V Application Binary Interface -- are both good
  945.      sources of DSO implementation details.
  946.  
  947.  
  948.